@Part[XPACK, Root = "CLM.MSS"]
@Comment{Chapter of Common Lisp Manual.  Copyright 1984 Guy L. Steele Jr.⎇

@mychapter[Packages]
@label[XPACK]


One problem with earlier @xlisp systems is the use of a single name space
for all symbols.  In large @xlisp systems, with modules written by many
different programmers, accidental name collisions become a serious
problem.  @clisp addresses this problem through the @i[package system],
derived from an earlier package system developed for
@lmlisp @cite[BLUE-LISPM].
In addition to preventing name-space conflicts, the
package system makes the modular structure of large @xlisp systems more
explicit.

A @i[package] is a data structure that establishes a mapping from print
names (strings) to symbols.  The package thus replaces the ``oblist'' or
``obarray'' machinery of earlier @xlisp systems.  At any given time one
package is current, and this package is used by the @xlisp reader in
translating strings into symbols.  The current package is, by definition,
the one that is the
value of the global variable @var[package].  It is possible to refer to
symbols in packages other than the current one through the use of
@i[package qualifiers] in the printed representation of the symbol.
For example, @f[foo:bar], when seen by the reader,
refers to the symbol whose name is
@f[bar] in the package whose name is @f[foo].
(Actually, this is true only if @f[bar] is an external symbol of @f[foo],
that is, a symbol that is supposed to be visible outside of @f[foo].
A reference to an internal symbol requires the intentionally
clumsier syntax @f[foo::bar].)

The string-to-symbol mappings available in a given package are divided
into two classes, @i[external] and @i[internal].  We refer to the
symbols accessible via these mappings as being @i[external] and
@i[internal] symbols of the package in question, though really it is the
mappings that are different and not the symbols themselves.  Within a
given package, a name refers to one symbol or to none; if it does refer
to a symbol, then it is either external or internal in that
package, but not both.

External symbols are part of the package's public interface to other
packages.  External symbols are supposed to be chosen with some care and are
advertised to users of the package.  Internal symbols are for internal
use only, and these symbols are normally hidden from other packages.
Most symbols are created as internal symbols; they become external only
if they appear explicitly in an @f[export] command for the package.

A symbol may appear in many packages.  It will always have the same
name wherever it appears, but it may be external in some packages
and internal in others.  On the other hand,
the same name (string) may refer to different symbols in
different packages.

Normally, a symbol that appears in one or more packages
will be @i[owned] by one particular package, called the @i[home package]
of the symbol; that package is said to @i[own] the symbol.
Every symbol has a component called the @i[package cell]
that contains a pointer to its home package.
A symbol that is owned by some package is said to be @i[interned].
Some symbols are not owned by any package; such a symbol
is said to be @i[uninterned], and its package cell contains @false.

Packages may be built up in layers.  From the point of view of a
package's user, the package is a single collection of mappings from
strings into internal and external symbols.  However, some of these
mappings may be established within the package itself, while other
mappings are inherited from other packages via the @f[use-package]
construct.  (The mechanisms responsible for this inheritance are
described below.)  In what follows, we will refer to a symbol as being
@i[accessible] in a package if it can be referred to
without a package qualifier when that package is current,
regardless of whether the mapping occurs within
that package or via inheritance.   We will refer to a symbol as being
@i[present] in a package if the mapping is in the package itself and is
not inherited from somewhere else.

A symbol is said to be @i[interned in a package x] if it is
accessible in that package and also is owned (by either that package
or some other package).  Normally all the symbols accessible in
a package will in fact be owned by some package,
but the terminology is useful when
discussing the pathological case of an accessible but unowned (uninterned)
symbol.

As a verb, to @i[intern] a symbol in a package means to cause the
symbol to be interned in the package if it was not already;
this process is performed by the function @Funref[intern].
If the symbol was previously unowned, then the package it is being
interned in becomes its owner (home package); but
if the symbol was previously owned by another package, that other package
continues to own the symbol.

To @i[unintern] a symbol from the package means to cause it to be not
present and, additionally, to make the symbol uninterned if the
package was the symbol's home package (owner).
This process is performed by the function @Funref[unintern].

@section[Consistency Rules]

Package-related bugs can be very subtle and confusing: things are not
what they appear to be.  The @clisp package system is designed with
a number of safety features to prevent most of the common bugs that
would otherwise occur in normal use.  This may seem over-protective, but
experience with earlier package systems has shown that such safety
features are needed.

In dealing with the package system, it is useful to keep in mind the
following consistency rules, which remain in force as long as the value
of @var[package] is not changed by the user or his code:

@begin [itemize]
@I[Read-read consistency:] Reading the same print name always results in
the same (@f[eq]) symbol.

@I[Print-read consistency:] An interned symbol always prints as a
sequence of characters that, when read back in, yields the same (@f[eq])
symbol.

@I[Print-print consistency:] If two interned symbols are not @f[eq], then
their printed representations will be different sequences of
characters.
@end [itemize]

These consistency rules remain true in spite of any amount of implicit
interning caused by typing in @xlisp forms, loading files, etc.  This has
the important implication that, as long as the current package
is not changed, results are reproducible regardless of
the order of loading files or the exact history of what symbols were
typed in when.  The rules can only be violated by explicit action:
changing the value of @var[package], forcing some action by continuing
from an error, or calling one of the ``dangerous'' functions
@Funref[unintern], @Funref[unexport], @Funref[shadow],
@Funref[shadowing-import], or @Funref[unuse-package].

@section[Package Names]

Each package has a name (a string) and perhaps some nicknames.  These
are assigned when the package is created, though they can be changed
later.  A package's name should be something long and self-explanatory,
like @f[editor]; there might be a nickname that is shorter and easier to
type, such as @f[ed].

There is a single name space for packages.  The function
@Funref[find-package] translates a package name or nickname into the
associated package.  The function @Funref[package-name] returns the name of a
package.  The function @Funref[package-nicknames] returns a list of all
nicknames for a package.  The function @Funref[rename-package] removes a
package's current name and nicknames and replaces them with new ones
specified by the user.  Package renaming is occasionally useful when, for
development purposes, it is desirable to load two versions of a package
into the same @xlisp.  One can load the first version, rename it,
and then load the other version, without getting a lot of name conflicts.

When the @xlisp reader sees a qualified symbol, it handles the package-name
part in the same way as the symbol part with respect to capitalization.
Lowercase characters in the package name are converted to corresponding
uppercase characters
unless preceded by the escape character @f[\] or
surrounded by @f[|] characters.  The lookup done by the
@f[find-package] function is case-sensitive, like that done for
symbols.  Note that @f[|Foo|:|Bar|] refers to a symbol whose name is
@f[Bar] in a package whose name is @f[Foo].  By contrast,
@f[|Foo:Bar|] refers to a seven-character symbol that has a colon in its name
(as well as two uppercase letters and four lowercase letters)
and is interned in the current package.  Following the convention used
in this manual for symbols, we will show ordinary package names using
lowercase letters, even though the name string is internally represented
with uppercase letters.

Most of the functions that require a package-name argument from the
user accept either a symbol or a string.  If the user supplies a symbol,
its print name will be used; the print name will already have undergone
case-conversion by the usual rules.  If the user supplies a string, he
must be careful to capitalize the string so as to match exactly the
string that names the package.

@section[Translating Strings to Symbols]
@label[STRING-TO-SYMBOL-SECTION]

The value of the special variable @var[package] must always be a package
object (not a name).  Whatever package object is currently the
value of @var[package] is referred to as the @i[current package].

When the @xlisp reader has, by parsing, obtained a string of characters
thought to name a symbol, that name is looked up in the current package.
This lookup may involve looking in other packages whose external symbols
are inherited by the current package.  If the name is found,
the corresponding symbol is returned.  If the name is not found
(that is, there is no symbol of that name accessible in the current package),
a new symbol is created for it and is placed in the current package as an
internal symbol.  Moreover, the current package becomes the owner
(home package) of the symbol, and so the symbol becomes interned
in the current package.
If the name is later read again while this same package is
current, the same symbol will then be found and returned.

Often it is desirable to refer to an external symbol in some package
other than the current one.  This is done through the use of a
@i[qualified name], consisting of a package name, then a colon, then the
name of the symbol.  This causes the symbol's name to be looked up
in the specified package, rather than in the current one.  For example,
@f[editor:buffer] refers to the external symbol named @f[buffer]
accessible in the package named @f[editor], regardless of whether
there is a symbol named @f[buffer] in the current package.  If there
is no package named @f[editor], or if no symbol named @f[buffer]
is accessible in @f[editor], or if @f[buffer] is an internal
symbol in @f[editor], the @xlisp reader will signal
a correctable error to ask the user what he really wants to do.

On rare occasions, a user may need to refer to an @i[internal] symbol of
some package other than the current one.  It is illegal to do this with
the colon qualifier, since accessing an internal symbol of some other
package is usually a mistake.  However, this operation is legal if
a doubled colon
@f[::] is used as the separator in place of the usual single colon.  If
@f[editor::buffer] is seen, the effect is exactly the same as
reading @f[buffer] with @var[package] temporarily rebound to the
package whose name is @f[editor].  This special-purpose qualifier
should be used with caution.

The package named @f[keyword] contains all keyword symbols used by the
@xlisp system itself and by user-written code.  Such symbols must be
easily accessible from any package, and name conflicts are not an issue
because these symbols are used only as labels and never to carry
package-specific values or properties.  Because keyword symbols are used
so frequently, @clisp provides a special reader syntax for them.
Any symbol preceded by a colon but no package name (for example
@f[:foo]) is added to (or looked up in) the @f[keyword] package as
an @i[external] symbol.  The @f[keyword] package is also treated
specially in that whenever a symbol is added to the @f[keyword] package
the symbol is always made external; the symbol
is also automatically declared to be a constant
(see @Macref[defconstant]) and made to
have itself as its value.  This is why every keyword evaluates to
itself.  As a matter of style, keywords should always be accessed using
the leading-colon convention; the user should never import or inherit
keywords into any other package.  It is an error to try to apply
@f[use-package] to the @f[keyword] package.

Each symbol contains a package cell that is used to record the home
package of the symbol, or @false if the symbol is uninterned.  This cell
may be accessed by using the function @Funref[symbol-package].
When an interned
symbol is printed, if it is a symbol in the keyword package,
then it is printed with a preceding colon; otherwise, if it is accessible
(directly or by inheritance) in the current package, it is printed
without any qualification; otherwise, it is printed with the name of the
home package as the qualifier, using @f[:] as the separator if the
symbol is external and @f[::] if not.

A symbol whose package slot contains @false (that is, has no home
package)
is printed preceded by @f[#:].  It is possible, by the
use of @Funref[import] and @Funref[unintern], to create a symbol that has no
recorded home package, but that in fact is accessible in some package.
The system does not check for this pathological case, and such symbols
will always be printed preceded by @f[#:].

In summary, the following four uses of symbol qualifier syntax are defined:

@Begin[description]
@f[foo:bar] @\When read, looks up @f[BAR] among the external symbols of
the package named @f[FOO].  Printed when symbol @f[bar] is external in its
home package @f[foo] and is not accessible in the current package.

@f[foo::bar] @\When read, interns @f[BAR] as if @f[FOO] were the
current package.  Printed when symbol @f[bar] is internal in its home package
@f[foo] and is not accessible in the current package.

@f[:bar] @\When read, interns @f[BAR] as an external symbol in the
@f[keyword] package, and makes it evaluate to itself.  Printed when
the home package of symbol @f[bar] is @f[keyword].
    
@f[#:bar] @\When read, creates a new uninterned symbol named @f[BAR].
Printed when the symbol @f[bar] is uninterned (has no home package),
even in the pathological case that @i[bar] is uninterned but
nevertheless somehow accessible in the current package.
@End[description]

All other uses of colons within names of symbols are not defined by
@clisp but are reserved for implementation-dependent use; this
includes names that end in a colon, contain two or more colons, or
consist of just a colon.

@section[Exporting and Importing Symbols]
@label[EXPORT-IMPORT-SECTION]

Symbols from one package may be made accessible in another package in
two ways.

First, any individual symbol may be added to a package by use
of the function @Funref[import].  The form @f[(import 'editor:buffer)] takes
the external symbol named @f[buffer] in the @f[editor] package (this
symbol was located when the form was read by the @xlisp reader) and adds
it to the current package as an internal symbol.  The symbol is then
present in the current package.  The imported symbol is
not automatically exported from the current package, but if it is
already present and external, then the fact that it
is external is not changed.  After the call to
@f[import] it is possible to refer to @f[buffer] in the importing package
without any qualifier.  The status of @f[buffer] in the package named
@f[editor] is unchanged, and @f[editor] remains the home package for
this symbol.  Once imported, a symbol is @i[present] in the
importing package and can be removed only by calling @f[unintern].

If the symbol is already present in the importing package, @f[import]
has no effect.  If a distinct symbol with the name @f[buffer] is
accessible in the importing package (directly or by inheritance), then a
correctable error is signalled, as described in
section @ref[NAME-CONFLICTS-SECTION], because @f[import] avoids letting
one symbol shadow another.

A symbol is said to be @i[shadowed] by another symbol in
some package if the first symbol would be accessible by inheritance
if not for the presence of the second symbol.
If the user really wants to import a symbol without the possibility
of getting an
error because of shadowing,
he should use the function @Funref[shadowing-import].  This inserts
the symbol into the specified package as an internal symbol, regardless
of whether another symbol of the same name will be shadowed by this
action.
If a different symbol of the same name is already present
in the package, that symbol will first be uninterned from the package
(see @Funref[unintern]).  The new symbol is
added to the package's shadowing-symbols list.  @f[shadowing-import]
should be used with caution.  It changes the state of the package system
in such a way that the consistency rules do not hold across the change.

The second mechanism is provided by the function @Funref[use-package].  This
causes a package to inherit all of the external symbols of some other
package.  These symbols become accessible as @i[internal] symbols of the
using package.  That is, they can be referred to without a qualifier
while this package is current, but they are not passed along to any
other package that uses this package.  Note that @f[use-package],
unlike @f[import], does not cause any new symbols to be @i[present]
in the current package but only makes them @i[accessible] by inheritance.
@f[use-package] checks carefully for
name conflicts between the newly imported symbols and those already
accessible in the importing package.  This is described in detail in
section @ref[NAME-CONFLICTS-SECTION].

Typically a user, working by default in the @f[user] package, will
load a number of packages into his @xlisp to provide an augmented working
environment; then he will call @f[use-package] on each of these packages
so that he can easily access their external symbols.
@f[unuse-package] undoes the effects of a previous @f[use-package].  The
external symbols of the used package are no longer inherited.  However,
any symbols that have been imported into the using package continue to
be present in that package.

There is no way to inherit the @i[internal] symbols of another package;
to refer to an internal symbol, the user must either make that symbol's home
package current, use a qualifier, or import that symbol into the current
package.

When @f[intern] or some other function wants to look up a symbol in a
given package, it first looks for the symbol among the external and
internal symbols of the package itself; then it looks through the
external symbols of the used packages in some unspecified order.  The
order does not matter; according to the rules for handling name
conflicts (see below), if conflicting symbols appear in two or more
packages inherited by package @i[X], a symbol of this name must also appear
in @i[X] itself as a shadowing symbol.  Of course, implementations are free
to choose other, more efficient ways of implementing this search, as
long as the user-visible behavior is equivalent to what is described
here.

The function @Funref[export] takes a symbol that is accessible in some
specified package (directly or by inheritance) and makes it an external
symbol of that package.  If the symbol is already accessible as an
external symbol in the package, @f[export] has no effect.  If the symbol
is directly present in the package as an internal symbol, it is simply
changed to external status.  If it is accessible as an internal symbol
via @f[use-package], the symbol is first imported into the package, then
exported.  (The symbol is then present in the specified package
whether or not the package
continues to use the package through which the symbol was originally
inherited.)  If the symbol is not
accessible at all in the specified package, a correctable error is
signalled that, upon continuing, asks the user whether the symbol
should be imported.

The function @Funref[unexport] is provided mainly as a way to undo erroneous
calls to @f[export].  It works only on symbols directly present
in the current package, switching them back to internal status.  If
@f[unexport] is given a symbol already accessible as an internal
symbol in the current package, it does nothing; if it is given a symbol
not accessible in the package at all, it signals an error.

@section[Name Conflicts]
@label[NAME-CONFLICTS-SECTION]

A fundamental invariant of the package system is that within one package
any particular name can refer to at most one symbol.  A @i[name conflict]
is said to occur when there is more than one candidate symbol and it is
not obvious which one to choose.  If the system does not always choose
the same way, the read-read consistency rule would be violated.  For
example, some programs or data might have been read in under a certain
mapping of the name to a symbol.  If the mapping changes to a different
symbol, and subsequently additional programs or data are read,
then the two programs will
not access the same symbol even though they use the same name.  Even if
the system did always choose the same way, a name conflict is likely to
result in a mapping from names to symbols different from what was expected by
the user, causing programs to execute incorrectly.  Therefore, any time
a name conflict is about to occur,
an error is signalled.  The user may continue
from the error and tell the package system how to resolve the conflict.

It may be that the same symbol is accessible to a package through more than
one path.  For example, the symbol might be
an external symbol of more than one used package, or the symbol
might be directly present in a package and also inherited from
another package.
In such cases there is no name conflict.
The same identical symbol cannot conflict with itself.
Name conflicts occur only between distinct symbols with
the same name.

The creator of a package can tell the system in advance how to resolve a
name conflict through the use of @i[shadowing].  Every package has a
list of shadowing symbols.  A shadowing symbol takes precedence over any
other symbol of the same name that would otherwise be accessible to the
package.  A name conflict involving a shadowing symbol is always
resolved in favor of the shadowing symbol, without signalling an error
(except for one exception involving @f[import] described below).  The
functions @Funref[shadow] and @Funref[shadowing-import] may be used to declare
shadowing symbols.

Name conflicts are detected when they become possible, that is, when the
package structure is altered.  There is no need to check for name
conflicts during every name lookup.

The functions @f[use-package], @f[import], and @f[export] check for name
conflicts.  @Funref[use-package] makes the external symbols of the package
being used accessible to the using package; each of these symbols is
checked for name conflicts with the symbols already accessible.
@Funref[import] adds a single symbol to the internals of a package, checking
for a name conflict with an existing symbol either present in the
package or accessible to it.  @f[import] signals a name conflict error
even if the conflict is with a shadowing symbol, the rationale being
that the user has given two explicit and inconsistent directives.
@Funref[export] makes a single
symbol accessible to all the packages that use the package from which
the symbol is exported.  All of these packages are checked for
name conflicts:  @f[(export @i[s] @i[p])] does
@f[(find-symbol (symbol-name @i[s]) @i[q])] for each package @i[q]
in @f[(package-used-by-list @i[p])].  Note that in the usual case of
an @f[export] during the initial definition of a package, the
result of @f[package-used-by-list]
will be @false and the name-conflict checking
will take negligible time.

The function @Funref[intern], which is the one used most
frequently by the @xlisp reader for looking up names of symbols,
does not need to do any name-conflict checking, because it
never creates a new symbol if there is already an accessible symbol with
the name given.

@f[shadow] and @f[shadowing-import] never signal a name-conflict error
because the user, by calling these functions, has specified how any
possible conflict is to be resolved.  @f[shadow] does name-conflict
checking to the extent that it checks whether a distinct existing symbol with
the specified name is accessible and, if so, whether it is directly
present in the package or inherited.  In the latter case, a new symbol
is created to shadow it.  @f[shadowing-import] does name-conflict
checking to the extent that it checks whether a distinct existing
symbol with the same name is accessible; if so, it is shadowed by
the new symbol, which implies that it must be uninterned
if it was directly present in the package.

@f[unuse-package], @f[unexport], and @f[unintern] (when the symbol being
uninterned is not a shadowing symbol) do not need to do any
name-conflict checking because they only remove symbols from a package;
they do not make any new symbols accessible.

Giving a shadowing symbol to @f[unintern] can uncover a name conflict that had
previously been resolved by the shadowing.  If package A uses packages
B and C, A contains a shadowing symbol @f[x], and B and C each contain external
symbols named @f[x], then removing the shadowing symbol @f[x]
from A will reveal a name
conflict between @f[b:x] and @f[c:x] if those two symbols are distinct.
In this case @f[unintern] will signal an error.

Aborting from a name-conflict error leaves the original symbol accessible.
Package functions always signal name-conflict errors before making any
change to the package structure.  When multiple changes are to be made,
however, for example when @f[export] is given a list of symbols, it is
permissible for the implementation to process each change separately,
so that aborting from a name
conflict caused by the second symbol in the list will not unexport the
first symbol in the list.  However, aborting from a name-conflict error
caused by @f[export] of a single symbol will not leave that symbol accessible
to some packages and inaccessible to others; with respect to
each symbol processed, @f[export]
behaves as if it were as an atomic operation.

Continuing from a name-conflict error should offer the user a chance to
resolve the name conflict in favor of either of the candidates.  The
package structure should be altered to reflect the resolution of the
name conflict, via @f[shadowing-import], @f[unintern], or @f[unexport].

A name conflict in @f[use-package] between a symbol directly present in the
using package and an external symbol of the used package may be resolved
in favor of the first symbol by making it a shadowing symbol, or in favor
of the second symbol by uninterning the first symbol from the using
package.  The latter resolution is dangerous if the symbol to be
uninterned is an external symbol of the using package, since it
will cease to be an external symbol.

A name conflict in @f[use-package] between two external symbols inherited
by the using package from other packages may be resolved in favor of
either symbol by importing it into the using package and making it a
shadowing symbol.

A name conflict in @f[export] between the symbol being exported and a
symbol already present in a package that would inherit the
newly-exported symbol may be resolved in favor of the exported symbol
by uninterning the other one, or in favor of the already-present
symbol by making it a shadowing symbol.

A name conflict in @f[export] or @f[unintern] due to a package
inheriting two distinct symbols with the same name from two other
packages may be resolved in favor of either symbol by importing it into
the using package and making it a shadowing symbol, just as with
@f[use-package].

A name conflict in @f[import] between the symbol being imported and a
symbol inherited from some other package may be resolved in favor of the
symbol being imported by making it a shadowing symbol, or in favor
of the symbol already accessible by not doing the @f[import].  A
name conflict in @f[import] with a symbol already present in the
package may be resolved by uninterning that symbol, or by not
doing the @f[import].

Good user-interface style dictates that @f[use-package] and @f[export],
which can cause many name conflicts simultaneously, first check for
all of the name conflicts before presenting any of them to the user.
The user may then choose to resolve all of them wholesale or to resolve
each of them individually, the latter requiring a lot of
interaction but permitting
different conflicts to be resolved different ways.

Implementations may offer other ways of resolving name conflicts.
For instance, if the symbols that conflict are not being used as
objects but only as names for functions, it may be possible to ``merge''
the two symbols by putting the function definition onto both symbols.
References to either symbol for purposes of calling a function would be
equivalent.  A similar merging operation can be done for variable values
and for things stored on the property list.  In @lmlisp, for example, one can
also @i[forward] the value, function, and property cells so that future
changes to either symbol will propagate to the other one.  Some other
implementations are able to do this with value cells but not with
property lists.  Only the user can know whether this way of resolving
a name conflict is adequate, because it will work only if
the use of two non-@f[eq]
symbols with the same name will not prevent the correct operation of
his program.  The value of offering symbol-merging as a way of resolving
name conflicts is that it can avoid the need to throw away the whole
@xlisp world, correct the package-definition forms
that caused the error, and start over from scratch.

@Section[Built-in Packages]

The following packages, at least, are built into every @clisp system:

@begin[description]
@f[lisp]@\The package named @f[lisp] contains the primitives of the
@clisp system.  Its external symbols include all of the
user-visible functions and global variables that are present in the
@clisp system, such as @f[car], @f[cdr], @var[package], etc.
Almost all other packages will want to use @f[lisp] so that these
symbols will be accessible without qualification.

@f[user]@\The @f[user] package is, by default, the current package at the time
a @clisp system starts up.  This package uses the @f[lisp] package.

@f[keyword]@\This package contains all of the keywords used by built-in
or user-defined @xlisp functions.  Printed symbol representations
that start with a colon are interpreted as referring to symbols
in this package, which are always external symbols.  All symbols in this
package are treated as constants that evaluate to themselves, so that the
user can type @f[:foo] instead of @f[':foo].

@f[system]@\This package name is reserved to the implementation.
Normally this is used to contain names of implementation-dependent
system-interface functions.  This package uses @f[lisp] and has the
nickname @f[sys]. 
@end[description]

@Section[Package System Functions and Variables]

Some of the functions and variables in this section
are described in previous sections but are included here
for completeness.

It is up to each implementation's compiler to ensure that when a
compiled file is loaded, all of the symbols in the file end up in the
same packages that they would occupy if the @xlisp source file were
loaded.  In most compilers, this will be accomplished by treating
certain package operations as though they are surrounded by
@f[(eval-when (compile load eval) ...)]; see @Specref[eval-when].
These operations are
@f[make-package], @f[in-package], @f[shadow], @f[shadowing-import],
@f[export], @f[unexport], @f[use-package], @f[unuse-package], and @f[import].
To guarantee proper compilation in all @clisp
implementations, these functions should appear only at top level within
a file.  As a matter of style, it is suggested that each file contain
only one package, and that all of the package setup forms appear near
the start of the file.  This is discussed in more detail, with examples,
in section @ref[PACKAGE-EXAMPLE-SECTION].

@implementation{In the past, some @xlisp compilers have read
the entire file into @xlisp before processing any of the forms.  
Other compilers have arranged for
the loader to do all of its intern operations before evaluating any of the
top-level forms.  Neither of these techniques will work in a
straightforward way in @clisp because of the presence of multiple
packages.⎇

For the functions described here, all optional arguments named
@i[package] default to the current value of @var[package].  Where a
function takes an argument that is either a symbol or a list of symbols,
an argument of @false is treated as an empty list of symbols.  Any
argument described as a package name may be either a string or a symbol.
If a symbol is supplied, its print name will be used as the package
name; if a string is supplied, the user must be take care to specify the
same capitalization used in the package name, normally all capitals.

@Defvar[Var {package⎇]
The value of this variable must be a package; this package is said to be
the current package.  The initial value of @var[package] is the @f[user]
package.

The function @Funref[load] rebinds @var[package] to its current value.  If
some form in the file changes the value of @var[package] during loading,
the old value will be restored when the loading is completed.
@Enddefvar

@Defun[Fun {make-package⎇, Args {@i[package-name]⎇, Keys {[nicknames][use]⎇]
This creates and returns a new package with the specified package name.  As
described above, this argument may be either a string or a symbol.  The
@Kwd[nicknames] argument must be a list of strings to be used as
alternative names for the package.  Once again, the user may supply
symbols in place of the strings, in which case the print names of the
symbols are used.  These names and nicknames must not conflict with
any existing package names; if they do, a correctable error is
signalled.

The @Kwd[use] argument is a list of packages or the names (strings or
symbols) of packages whose external symbols are to be inherited by the
new package.  These packages must already exist.  If not supplied,
@Kwd[use] defaults to a list of one package, the @f[lisp] package.
@Enddefun

@Defun[Fun {in-package⎇, Args {@i[package-name]⎇, Keys {[nicknames][use]⎇]
The @f[in-package] function is intended to be placed at the start of a
file containing a subsystem that is to be loaded into some package other
than @f[user].  If there is not already a package named @i[package-name], this
function is similar to @f[make-package], except that after the
new package is created, @var[package] is set to it.  This binding will
remain in force until changed by the user (perhaps with another
@f[in-package] call) or until the @var[package] variable reverts to its
old value at the completion of a @f[load] operation.

If there is an existing package whose name is @i[package-name], the
assumption is that the user is re-loading a file after making some
changes.  The existing package is augmented to reflect any new nicknames
or new packages in the @Kwd[use] list (with the usual error checking), and
@var[package] is then set to this package.
@enddefun

@Defun[Fun {find-package⎇, Args {@i[name]⎇]
The @i[name] must be a string that is the name or nickname for a
package.  This argument may also be a symbol, in which case the symbol's
print name is used.  The package with that name or nickname
is returned; if no such package exists, @f[find-package] returns @false.
The matching of names observes case
(as in @Xfunref[X {string=⎇, L {string#&M⎇]).
@Enddefun

@Defun[Fun {package-name⎇, Args {@i[package]⎇]
The argument must be a package.  This function returns the string that
names that package.
@Enddefun

@Defun[Fun {package-nicknames⎇, Args {@i[package]⎇]
The argument must be a package.  This function returns the list of
nickname strings for that package, not including the primary name.
@Enddefun

@Defun[Fun {rename-package⎇, Args {@i[package] @i[new-name] @optional @i[new-nicknames]⎇]
The old name and all of the old nicknames of @i[package] are eliminated
and are replaced by @i[new-name] and @i[new-nicknames].  The
@i[new-name] argument is a string or symbol; the @i[new-nicknames]
argument, which defaults to @false, is a list of strings or symbols.
@Enddefun

@Defun[Fun {package-use-list⎇, Args {@i[package]⎇]
A list of other packages used by the argument package is returned.
@Enddefun

@Defun[Fun {package-used-by-list⎇, Args {@i[package]⎇]
A list of other packages that use the argument package is returned.
@Enddefun

@Defun[Fun {package-shadowing-symbols⎇, Args {@i[package]⎇]
A list is returned of symbols that have been declared as shadowing
symbols in this package by @f[shadow] or @f[shadowing-import].  All
symbols on this list are present in the specified package.
@Enddefun

@Defun[Fun {list-all-packages⎇, Args {⎇]
This function returns a list of all packages that currently exist in the
@xlisp system.
@Enddefun

@Defun[Fun {intern⎇, Args {@i[string] @optional @i[package]⎇]
The @i[package], which defaults to the current package, is
searched for a symbol with the name specified by the @i[string]
argument.  This search will include inherited symbols, as described
in section @ref[EXPORT-IMPORT-SECTION].
If a symbol with the specified name is found, it is returned.
If no such symbol is found, one is created and is installed in the
specified package as an internal symbol (as an external symbol
if the package is the @f[keyword] package); the specified package becomes the
home package of the created symbol.

Two values are returned.  The first is the symbol that was found or
created.  The second value is @false if no pre-existing symbol was found,
and takes on one of three values if a symbol was found:
@Randomkeywordlist{second value from @f[intern]⎇
@RandomKeyword[internal]
The symbol was directly present in the package as an internal symbol.
@EndRandomKeyword

@RandomKeyword[external]
The symbol was directly present as an external symbol.
@EndRandomKeyword

@RandomKeyword[inherited]
The symbol was inherited via @f[use-package] (which
implies that the symbol is internal).
@EndRandomKeyword
@EndRandomKeywordList

@Incompatibility{Conceptually, @f[intern] translates a
string to a symbol.  In @Maclisp and several other dialects of @xlisp,
@f[intern] can take either a string or a symbol as its argument; in the 
latter case, the symbol's print name is extracted and used as the string.  
However, this leads to some confusing issues about what to do if
@f[intern] finds a symbol that is not @f[eq] to the argument symbol.  To
avoid such confusion, @clisp requires the argument to be a string.⎇
@Enddefun

@Defun[Fun {find-symbol⎇, Args {@i[string] @optional @i[package]⎇]
This is identical to @f[intern], but it never creates a new symbol.  If
a symbol with the specified name is found in the specified package,
directly or by inheritance, the symbol found is returned as the first
value and the second value is as specified for @f[intern].  If the
symbol is not accessible in the specified package, both values are
@false.
@Enddefun

@Defun[Fun {unintern⎇, Args {@i[symbol] @optional @i[package]⎇]
If the specified symbol is present in the specified @i[package], it is
removed from that package and also from the package's shadowing-symbols
list if it is present there.  Moreover, if the @i[package] is the home
package for the symbol, the symbol is made to have no home package.
Note that in some circumstances the symbol may continue to be accessible
in the specified package by inheritance.
@f[unintern] returns @true if it actually removed a symbol,
and @false otherwise.

@f[unintern] should be used with caution.  It changes the state of the
package system in such a way that the consistency rules do not hold
across the change.
@Incompatibility{The equivalent of this in @maclisp is @f[remob].⎇
@Enddefun

@Defun[Fun {export⎇, Args {@i[symbols] @optional @i[package]⎇]
The @i[symbols] argument should be a list of symbols, or possibly a single
symbol.  These symbols become accessible as external symbols in
@i[package].
See section @ref[EXPORT-IMPORT-SECTION] for details.
@f[export] returns @true.

By convention, a call to @f[export] listing all exported symbols is
placed near the start of a file to advertise which of the symbols
mentioned in the file are intended to be used by other programs.
@Enddefun

@Defun[Fun {unexport⎇, Args {@i[symbols] @optional @i[package]⎇]
The argument should be a list of symbols, or possibly a single symbol.
These symbols become internal symbols in @i[package].
It is an error to unexport a symbol from the @f[keyword] package.
See section @ref[EXPORT-IMPORT-SECTION] for details.
@f[unexport] returns @true.
@Enddefun

@Defun[Fun {import⎇, Args {@i[symbols] @optional @i[package]⎇]
The argument should be a list of symbols, or possibly a single symbol.
These symbols become internal symbols in @i[package] and can therefore
be referred to without having to use qualified-name (colon) syntax.
@f[import] signals a
correctable error if any of the imported symbols has the same name as
some distinct symbol already accessible in the package.
See section @ref[EXPORT-IMPORT-SECTION] for details.
@f[import] returns @true.
@Enddefun

@Defun[Fun {shadowing-import⎇, Args {@i[symbols] @optional @i[package]⎇]
This is like import, but it does not signal an error even if the
importation of a symbol would shadow some symbol already accessible in
the package.  In addition to being imported, the symbol is placed on the
shadowing-symbols list of @i[package].
See section @ref[NAME-CONFLICTS-SECTION] for details.
@f[shadowing-import] returns @true.

@f[shadowing-import] should be used with
caution.  It changes the state of the package system in such a way that
the consistency rules do not hold across the change.
@Enddefun

@Defun[Fun {shadow⎇, Args {@i[symbols] @optional @i[package]⎇]
The argument should be a list of symbols, or possibly a single symbol.
The print name of each symbol is extracted, and the specified package is
searched for a symbol of that name.  If such a symbol is present in this
package (directly, not by inheritance), then nothing is done.  Otherwise,
a new symbol is created with this print name, and it is inserted in the
specified package as an internal symbol.  The symbol is also placed on the
shadowing-symbols list of @i[package].
See section @ref[NAME-CONFLICTS-SECTION] for details.
@f[shadow] returns @true.

@f[shadow] should be used with
caution.  It changes the state of the package system in such a way that
the consistency rules do not hold across the change.
@Enddefun

@Defun[Fun {use-package⎇, Args {@i[packages-to-use] @optional @i[package]⎇]
The @i[packages-to-use] argument should be a list of packages or package
names, or possibly a single package or package name.  These packages are
added to the use-list of @i[package] if they are not there already.  All
external symbols in the packages to use become accessible in @i[package]
as internal symbols.
See section @ref[EXPORT-IMPORT-SECTION] for details.
It is an error to try to use the @f[keyword] package.
@f[use-package] returns @true.
@enddefun

@Defun[Fun {unuse-package⎇, Args {@i[packages-to-unuse] @optional @i[package]⎇]
The @i[packages-to-unuse] argument should be a list of packages or
package names, or possibly a single package or package name.  These
packages are removed from the use-list of @i[package].
@f[unuse-package] returns @true.
@enddefun

@Defun[Fun {find-all-symbols⎇, Args {@i[string-or-symbol]⎇]
@f[find-all-symbols]
searches every package in the @xlisp system to find
every symbol whose print name is the
specified string.  A list of all such symbols found is returned.
This search is case-sensitive.
If the argument is a symbol, its print name supplies
the string to be searched for.
@enddefun

@Defmac[Fun {do-symbols⎇, Args {(@i[var] @Mopt<@i[package] @Mopt'@i[result-form]'>) @Mstar<@i[declaration]> @mstar<@i[tag] @mor @i[statement]>⎇]
@f[do-symbols] provides straightforward iteration over the symbols of a
package.  The body is performed once for each symbol accessible in the
@i[package], in no particular order, with the variable @i[var] bound to
the symbol.  Then @i[result-form] (a single form, @i[not] an implicit
@f[progn]) is evaluated, and the result is the value of the
@f[do-symbols] form.  (When the @i[result-form] is evaluated, the control
variable @i[var] is still bound and has the value @false.)  If the
@i[result-form] is omitted, the result is @false.  @Macref[return] may be used
to terminate the iteration prematurely.  If execution of the body affects
which symbols are contained in the @i[package], other than possibly to
remove the symbol currently the value of @i[var] by using @f[unintern],
the effects are unpredictable.
@Enddefmac

@Defmac[Fun {do-external-symbols⎇, Args {(@i[var] @Mopt<@i[package] @Mopt'@i[result]'>) @Mstar<@i[declaration]> @mstar<@i[tag] @mor @i[statement]>⎇]
@f[do-external-symbols] is just like @f[do-symbols], except that only
the external symbols of the specified package are scanned.
@Enddefmac

@Defmac[Fun {do-all-symbols⎇, Args {(@i[var] @Mopt<@i[result-form]>) @Mstar<@i[declaration]> @mstar<@i[tag] @mor @i[statement]>⎇]
This is similar to @f[do-symbols] but executes the body once for every
symbol contained in every package.  (This will not process every symbol
whatsoever, because a symbol not accessible in any package will not
be processed.  Normally, uninterned symbols are not accessible in any package.)
It is @i[not] in general
the case that each symbol is processed only once, because a symbol may
appear in many packages.
@Enddefmac

@Section[Modules]

A @i[module] is a @clisp subsystem that is loaded from one or more
files.  A module is normally loaded as a single unit, regardless of how
many files are involved.  A module may consist of one package or several
packages.  The file-loading process is necessarily
implementation-dependent, but @clisp provides some very simple
portable machinery for naming modules, for keeping track of which modules
have been loaded, and for loading modules as a unit.

@Defvar[Var {modules⎇]
The variable @var[modules] is a list of names of the modules
that have been loaded into the @xlisp system so far.
This list is used by the functions @f[provide] and @f[require].
@enddefvar

@Defun[Fun {provide⎇, Args {@i[module-name]⎇]
@Defun1[Fun {require⎇, Args {@i[module-name] @optional @i[pathname]⎇]
Each module has a unique name (a string).  The @f[provide] and @f[require]
functions accept either a string or a symbol as the @i[module-name]
argument.  If a symbol is provided, its print name is used as the module
name.  If the module consists of a single package, it is customary for
the package and module names to be the same.

The @f[provide]
function adds a new module name to the list of modules
maintained in the variable @Var[modules], thereby indicating that
the module in question has been loaded.

The @f[require] function tests whether a module is already present
(using a case-sensitive comparison); if the module is not present,
@f[require] proceeds to load the appropriate
file or set of files.  The pathname argument, if present, is a single
pathname or a list of pathnames whose files are to be loaded in order,
left to right.  If the pathname argument is @false or is not provided, the
system will attempt to determine, in some
system-dependent manner, which files to load.
This will typically involve some central
registry of module names and the associated file lists.
@Implementation{One way to implement such a registry on
many operating systems is simply to use a distinguished ``library''
directory within the file system, where the name of each file
is the same as the module it contains.⎇
@enddefun

@section[An Example]
@label[PACKAGE-EXAMPLE-SECTION]

Most users will want to load and use packages but will never need to
build one.  Often a user will load a number of packages into the
@f[user] package whenever he uses @clisp.  Typically an implementation
might provide some sort of initialization file  mechanism to make such setup
automatic when the @xlisp starts up.  Table @ref[INIT-FILE-TABLE]
shows such an initialization file, one that simply
causes other facilities to be loaded.

@Begin[Table]
@Mline[]
@Caption[An Initialization File]
@Tag[INIT-FILE-TABLE]
@lisp
;;;; Lisp init file for I. Newton.

;;; Set up the USER package the way I like it.

(require 'calculus)		;I use CALCULUS a lot.  Load it.
(use-package 'calculus)		;Get easy access to its
				; exported symbols.

(require 'newtonian-mechanics)	;Same thing for NEWTONIAN-MECHANICS.
(use-package 'newtonian-mechanics)

;;; I just want a few thing from RELATIVITY,
;;; and other things conflict.
;;; Import only what I need into the USER package.

(require 'relativity)
(import '(relativity:speed-of-light
	  relativity:ignore-small-errors))

;;; These are worth loading, but I will use qualified names,
;;; such as PHLOGISTON:MAKE-FIRE-BOTTLE, to get at any symbols
;;; I might need from these packages.

(require 'phlogiston)
(require 'alchemy)

;;; End of Lisp init file for I. Newton.
@endlisp		
@Mline[]
@End[Table]

When each of two files uses some symbols from the other, one must be
careful to arrange the contents of the file in the proper order.
Typically each file contains a single package that is a complete module.
The contents of such a file should include the following items, in
order:

@Begin[enumerate, spread .2]
A call to @f[provide] that announces the module name.

A call to @f[in-package] that establishes the package.

A call to @f[shadow] that establishes any local symbols that will shadow
symbols that would otherwise be inherited from packages that this
package will use.

A call to @f[export] that establishes all of this package's external
symbols.

Any number of calls to @f[require] to load other modules that the
contents of this file might want to use or refer to.  (Because the
calls to @f[require] follow the calls to @f[in-package],
@f[shadow], and @f[export], it is possible for the packages that may
be loaded to refer to external symbols in this package.)

Any number of calls to @f[use-package], to make external
symbols from other packages accessible in this package.

Any number of calls to @f[import], to make
symbols from other packages present in this package.

Finally, the definitions making up the contents of this package/module.
@End[enumerate]

The following mnemonic sentence may be helpful in remembering
the proper order of these calls:
@Begin[Center]
@b[Put in seven extremely random user interface commands.]
@End[Center]
Each word of the sentence corresponds to one item in the above ordering:
@Begin[Format, LeftMargin +2in]
@tabset[+1.2 in]
Put@\@f[Provide]
IN@\@f[IN-package]
Seven@\@f[Shadow]
EXtremely@\@f[EXport]
Random@\@f[Require]
USEr@\@f[USE-package]
Interface@\@f[Import]
COmmands@\COntents of package/module
@End[Format]
The sentence says what it helps you to do.

@Begin[FullPageTable]
@Mline[]
@Caption[File @f[alchemy]]
@Tag[ALCHEMY-FILE-TABLE]
@lisp
;;;; Alchemy functions, written and maintained by Merlin, Inc.

(provide 'alchemy)		;The module is named ALCHEMY.
(in-package 'alchemy)		;So is the package.

;;; There is nothing to shadow.

;;; Here is the external interface.

(export '(lead-to-gold gold-to-lead 
          antimony-to-zinc elixir-of-life))

;;; This package/module needs a function from
;;; the PHLOGISTON package/module.

(require 'phlogiston)

;;; We don't frequently need most of the external symbols from
;;; PHLOGISTON, so it's not worth doing a USE-PACKAGE on it.
;;; We'll just use qualified names as needed.  But we use
;;; one function, MAKE-FIRE-BOTTLE, a lot, so import it.
;;; It's external in PHLOGISTON, and so can be referred to
;;; here using ":" qualified-name syntax.

(import '(phlogiston:make-fire-bottle))

;;; Now for the real contents of this file.

(defun lead-to-gold (x)
  "Takes a quantity of lead and returns gold."
  (when (> (phlogiston:heat-flow x)  ;Using a qualified symbol.
	   3)
    (make-fire-bottle x))	     ;Using an imported symbol.
  (gild x))

;;; And so on ...
@endlisp
@Mline[]
@End[FullPageTable]

@Begin[FullPageTable]
@Mline[]
@Caption[File @f[phlogiston]]
@Tag[PHLOGISTON-FILE-TABLE]
@lisp
;;;; Phlogiston functions, by Thermofluidics, Ltd.

(provide 'phlogiston)		;The module is named PHLOGISTON.
(in-package 'phlogiston)	;So is the package.

;;; There is nothing to shadow.

;;; Here is the external interface.

(export '(heat-flow cold-flow mix-fluids separate-fluids
	  burn make-fire-bottle))

;;; This file uses functions from the ALCHEMY package/module.

(require 'alchemy)

;;; We use alchemy functions a lot, so use the package.
;;; This will allow symbols exported from the ALCHEMY package
;;; to be referred to here without the need for qualified names.

(use-package 'alchemy)

;;; No calls to IMPORT are needed here.

;;; The real contents of this package/module.

(defun heat-flow (amount x y)
  "Make some amount of heat flow from x to y."
  (when feeling-weak
    (quaff (elixir-of-life)))		;No qualifier needed.
  (push-heat amount x y))

;;; And so on ...
@endlisp
@Mline[]
@End[FullPageTable]

Now, suppose for the sake of example
that the @f[phlogiston] and @f[alchemy] packages are
single-file, single-package modules as described above.  The @f[phlogiston]
package needs to use the @f[alchemy] package, and the @f[alchemy] package
needs to use several
external symbols from the @f[phlogiston] package.
The definitions in the @f[alchemy] and @f[phlogiston] files
(see Tables @ref[ALCHEMY-FILE-TABLE] and @ref[PHLOGISTON-FILE-TABLE])
allow a
user to specify @f[require] statements for either of these modules, or for
both of them in either order, and all relevant information will be
loaded automatically and in the correct order.

For very large modules whose contents are spread over several files
(the @f[lisp] package is an example), it is recommended that the user
create the package and declare all of the shadows and external symbols
in a separate file, so that this can be loaded before anything that
might use symbols from this package.